******************************************************************* * * * (C) Copyright International Business Machines Corporation 1993. * * All rights Reserved. * * * ******************************************************************* ALPHA V2.5 Lionel de Lambert - Iunius MMDCCXLIII AUC IBM United Kingdom Laboratories Ltd. 1 May 1995 This document describes the installation, function and commands of the ALPHA software analysis programme which runs under the OS/2 v2.0 or later operating system. The languages supported are :- 370 and 386 assembler, PASCAL(Ada), PL/X(PL/I, REXX), C(C++), and FORTRAN. Description =========== This is a simple 32-bit configurable multi-document highlighting editor version of the alpha software analysis programmes which were written together with the CMS programme ANALYSE in order to establish the praecognita for the CICS restructure project and may be of interest to those people who examine 370, 386 assembler, PASCAL(Ada), PL/X(PL/I, REXX), C(C++), FORTRAN etc. under OS/2 V2.0 or later. This programme will provide basic browse and edit functions for all files with arbitarily long records, {records >= 256 will be split for display and rejoined when saved} as well as highlighting specified keywords for language files such as 370 & 386 Assemble, PASCAL, PL/AS, C(CPP), FORTRAN etc. ALPHA will also display the programme call structure, and expand the procedure calls in a secondary window. This version of Alpha was written in C-Set/2 and MASM V6.0 and will run on OS/2 V2.0 or later. Highlighting of keywords has been provided for the following language types :- A37,ASM,PAS,(PLS,PLX,PLI),(C,CPP,H),FOR,IPF The syntax of the Alpha programme is :- START ALPHA [file] [/p [profile name - default ALPHA.PRF]] The Language_colour, Language_operator, Precedent_C, File_type, Comment_start, Comment_end, String_start, Transfer_pgm(1) and Window keywords are the only ones which are recognized from the profile. {The main window position is remembered when Alpha is closed.} Installation ============ The minimum requirement is to copy the file ALPHA.EXE to a directory under OS/2 v2.x. If you want to access the Extended help you must copy the file ALPHA.HLP in to the HELP path. If you wish to use the Alpha fonts you should copy the ALPHA.FON file to a directory under OS/2 v2.x and select 'System Setup' from 'OS/2 System' and use 'Add' in the 'Edit font' of the 'Font Palette'. If you wish to access files from the host then you should also install a file transfer programme such as ALMCOPY. Features ======== This version of Alpha provides the following features :- - Basic browse and edit functions. + Copy, cut and paste. + Box mode {column mode} select as well as line mode. + Special character insert for diagrams etc.. + Display characters at the current cursor position in Hex and instructions. - Invokes the appropriate compiler. - Cross-references labels. - Searches files in a directory for a string. - Displays the program call structure. - Highlights keywords. - Suppression of selected lines. - Suppression of comments. - Expands the procedure call in a secondary window. - Search of compiler include paths. - Conversion to upper or lower case. - Clearing selected areas to blanks. - Tab expansion. - Customization for highlighting and language support. - Bookmark support. - Dis-assemble ".EXE" files. - Edit/analyse up to 256 files at a time. Menu ==== The Allocate dialogue box is used to request a file to be read. If the drive letter is changed then the OK button should be used to refresh the List boxes. A file may also be allocated by dragging mouse button 2 with the Ctrl key pressed from a Drives window and releasing it over the Alpha window. {The maximum number of child windows is 256.} The Profile button may be used to remember the file name entered in the Combo box as the profile for subsequent invocations. This will obviate the need for the '/p' option and allow the dropping of files on the unstarted programme. A null file name will remove the saved profile name. The Transfer button will pass the contents of the Combo box to the Transfer_pgm. The Command dialogue box(2) may be used to issue a search command e.g. Non-case sensitive search for a string. Case sensitive search for a string. Case sensitive search for a string in column one. (The string search starts from the current cursor position +1.) Move to a specified line number. Replace the text at the current cursor position with the text from the Replacement Text Entry Box. Options ======= The Options menue may be used to set the following options :- Statement No. - display the statement number in the TITLE bar. Tab - expand the record by using X'09' characters to round to columns n*8. Keyword - highlight the keywords. Include - For the file types of MASM, PASCAL, PL/S {PL/I etc.} and C read the include files specified by :- include file_name, {$INCLUDE : 'file_name' }, %INCLUDE first_part_of_file_name;, #include , respectively when expanding a call etc. {The current directory together with the paths defined by the INCLUDE environment variable will be searched. The total number of open files/windows is limited to 256 so the include nesting level can not exceed 256 - the number of open windows. For language 4, PL/S, the file extension is appended to the first_part_of_file_name.} Grid - Draw vertical grid lines through every tenth character in the Grid colour and flag lines greater than 80 characters long. Records greater than 256 characters, continued, will be flagged with the highlight colour. Box - Switch the select mode to box format. In box mode the "Paste" function will overwrite the text at the cursor position with the box area. Tool bar - Display the "Tool bar"; which makes toggling of some options easy. Configure ========= This will invoke the Configure notebook with the following pages :- C - Colour - Set the text colour F - Font - set the text font. T - Configure the Tool bar. Font ---- The Font dialogue box may be used to change and remember the font of the text, comments etc. You can use the System Monospaced, Helvetica, Roman and Courier fonts but the Courier, System VIO and the System Monospaced fonts are the only monospaced fonts supplied with OS/2 V2.x. A monospaced font with point sizes 8,9,10,11,16 & 20 is supplied with the ALPHA PACKAGE, which may also be used. Outline fonts are not selectable. Point sizes (1/72") are :- Courier (8,10,12), Roman (8,10,12,14,18,24), Helvetica (8,10,12,14,18,24), System (8,10,12, {8x8, 8x16,9x20}), "Alpha" (8{8x12},9{9x10},10{8x14},11{11x12},16{12x16},20{12x20}). The Alpha font point size 10 is suitable for 8513 screens and the point size 20 for 8515/8516. Colour ------ The Colour dialogue box may be used to change and remember the colours(3) of the text, comments etc. The following colours may be changed with this dialog box :- Text - The main text colour. Background - The text background colour. Comment/statement# - The Comment colour, statement number and Structure List box calls. Comment background - The background colour for the comment text. Select text - The mouse button 1 drag area text colour. Select background - The mouse button 1 drag area background colour. String - The string text colour. String background - The string background colour. Highlight - The mouse button 1 isolate keyword. Locate/Position - The mouse button 2 locate string, the character position of the last mouse button 1 click and the Structure List box procedures. Branch - The Branch/Jump instruction colour. Grid/Help balloon - The vertical grid line colour and the Tool bar help balloon background. Help balloon - The Tool bar help balloon colour. Configure Tool bar ------------------ This Dialog box may be used to Delete or Add buttons to the Tool bar and to change its size and orientation. - The Buttons List box contains the available buttons; one should be selected and the Add button pressed to add it to the Tool bar. - The Tool bar List box shows the current list of buttons in the Tool bar; one should be selected and the Delete button pressed to remove it. - The Entry box displays the current button size which may be changed. - The Horizontal and vertical Radio buttons will read the Entry box and reconstruct the Tool bar. - The menu Radio button will cause the Tool bar to be placed in the menu when Alpha is restarted. - The Configure button will cause the changes to be applied. The new Tool bar structure will be remembered when Alpha is closed. If the Tool bar is changed from menu to floating then Alpha should be closed and restarted. The Print dialogue box may be used to print a range of records on one of :- LPT1, LPT2, LPT3. If a range of records has been selected by dragging the mouse with button one down then this range will be used in the print dialogue box. The default record range is the whole file. The Window menu may be used to close all child windows or to arrange them so that the title text is visible, Cascade, or so that a partial view of each child may be seen, Tile. The Select window option will create a dialogue box from which a child window may be selected to become the active widow. The first eight windows may be selected by file name from this menu. The Edit dialogue box may be used to edit the current line :- ---- - The Multi-Line Entry box may be used to modify the current line or add new lines. The number of lines added is the No. of lines in the MLE. - The Modify button will replace the current line with the contents of the MLE. - The Undo button will undo the changes to the MLE. - The Cancel button will leave the current line unchanged. - The number on the left shows the current cursor position in the MLE. - The number on the right shows the current pointer, mouse, position in the MLE. The current line is the top line in the window unless button 1 has been pressed when the cursor will indicate the line. If major modifications, {The Multi-line Entry field will only accept 64 lines at a time}, are to be made to the file then a purpose built editor should be used. The records >= 256 characters will be split for display and rejoined when saved. The Select character character dialogue box ---------------- will allow one of the 256 characters from the current font to be inserted at the current cursor position. Select one character by pressing mouse button 1 on the required character of the array. Use the System menu to dismiss the dialogue box. This may be used to draw diagrams etc. ÉÍÍËÍÍ» ÌËÍÎÍ͹ ÌÎÍÎÍ͹ ÈÊÍÊÍͼ Help ---- The Help menu may be used to display the About window, the Help summary window or access the OS/2 help file ALPHA.HLP(5). The Help summary window may be scrolled by :- Page_up - scroll up 1 screen Page_down - scroll down 1 screen Home - scroll to the top of the Help data End - scroll to the end of the Help data Up_arrow - scroll up 1 line. Down_arrow - scroll down 1 line. The mouse button 1 will highlight a string and mouse button 2 will cause a case sensitive search for this string from the current cursor position +1, {if the Ctrl key is held down then the search is not case sensitive}. If the Ctrl key is held down when the mouse button 1 is pressed then a Pop-up menu will be displayed which will allow either the Select character or Edit dialog boxes to be displayed. If mouse button 1 is clicked twice on a label then a search from the top of the file is made for the label definition or procedure entry and a secondary window is opened, Expand. {The language structure tables are searched first so if you have specified some structure keywords via. Language_operator then you will have to record the structure first, Ctrl+s.} If mouse button 1 is clicked twice on BEGIN for PASCAL, { for C or DO for PL/S then the following records up to the matching END etc. will not be displayed. If the mouse button 1 is double clicked on the suppressed message line or F12 is pressed then the records will be re-displayed. If the mouse button 1 is double clicked on a child window containing an "EXE" file which has an LX header record then a second child window containing the dis-assembled code object will be created. If the Include option is effective and mouse button 1 is double clicked on an Include statement then a second window containing the include file will be created. The following keys are effective for the programme - F1 will open the Help window. F2 will open the Configure Notebook. F3 will close the programme. F4 will open the Allocate file dialogue box. F5 will repeat the previous command. F6 will open the Command dialogue box. F7 will scroll the window up 1/2 a screen. F8 will scroll the window down 1/2 a screen. F12 will reset the collapse of the BEGIN/END pairs etc. Page_Up will scroll up 1 screen. Page_Down will scroll down 1 screen. The Home key will scroll to the top of the file. The End key will scroll to the end of the file. Up_arrow - scroll up 1 line. Down_arrow - scroll down 1 line. Left_arrow - scroll left 1 column. Right_arrow - scroll right 1 column. (Hold down the Shift key to highlight an area of the window.) The Insert key will toggle the Insert/Overwrite mode for character Edit in the Child window at the current cursor position. The Insert+Shift keys will insert the lines from the Clipboard at the current cursor position. The Insert+Ctrl keys will copy the lines highlighted by the button(4) 1 drag area from the display to the Clipboard. The Delete key will delete the character or select area at the current cursor position in the child window. The Delete+Shift keys will copy the selected area to the Clipboard and delete the text. The Space+Ctrl keys will clear the selected area to blanks. The Ctrl+b keys will re-insert the last deleted records. The Ctrl+e keys will edit the current line. The current line will be the top line in the window unless button 1 has been pressed when the cursor will indicate the the line. The Ctrl+g keys will search the current directory for a string. The Ctrl+h keys will hide/restore the selected lines. The Ctrl+shift+s keys will save the current file. The Ctrl+s keys will record or display the programme structure. {The programme calling structure will be recorded if this has not already been done and then the Structure dialog box will be displayed. If an entry from the List box is selected then the last active window will be scrolled to that line. The Print button may be used to print the contents of the List box on LPT1. The calling structure is based on the profile keywords :- Language_operator, Precedent_C and File_type. If the file contains tab characters then Tab expansion must be active before the structure is recorded.} The Ctrl+u will convert the select area to upper or lower case. If the first character of the selected area is upper case then the area is converted to lower case otherwise the area is converted to upper case. The Ctrl+x keys will display the record references to the highlighted label, XREF. The Ctrl+c keys will suppress/display the comments in a language file. If a single line is scrolled then the comment suppression will be disabled. The Ctrl+Shift+c keys will compile the last active file using the command displayed in the Compile dialogue box which will be scanned and the % replaced by the file name from the file entry box. The resultant command will be executed when the Execute button is pressed. The Standard Output for the Child process will be written to the "Output" MLE. The programme name is formed by appending ".EXE" to the first name of the command line. If the command line is modified then it will be remembered when Alpha is closed. The maximum text size for the command is 128 characters. Other programmes could be executed e.g. GREP -y -l "%" *.C The Alt+n keys will record a bookmark, where n is a numeric key 0-9. The Ctrl+n keys will move to the bookmark. Search ====== The Search dialogue box may be used to search the current directory for a string. - The Argument Entry box specifies the search string, the default is the highlight string. - The File type Entry box specifies the file extension, the default is the first extension for the language of the last active window or 'C'. The files searched are of the type '*.file_extension' in the current directory. - The List box displays the found lines. If one is selected and the GoTo button pressed then a child window will be created for the file. - The Locate button will search the current directory for the Argument string and fill the List box. - The Cancel button will dismiss the Dialogue box. - The Case sensitive Check box specifies whether the search is to be case sensitive or not. XREF ==== The XREF dialogue box may be used to search the records of the last active window for a string. - The Argument Entry box specifies the search string, the default is the highlight string. - The List box displays the found lines. If one is selected and the GoTo button pressed then the last active child window will be scrolled to that line. - The Locate button will search the last active child window's records for the Argument string and fill the List box. - The Cancel button will dismiss the Dialogue box. - The Case sensitive Check box specifies whether the search is to be case sensitive or not. - The Keyword Check box specifies whether the string should be terminated by a non-alphanumeric character. Profile ======= A profile(6) may be specified defining the following keyword values, these are the only ones recognized by the Alpha programme:- File_type specifies the File types to be recognized. The string must be <=64 characters and terminated by a comma. The first 6 types are used for :- 370 assembler 386 assembler PASCAL, (Ada) PL/S, PL/AS, PL/I etc., (REXX) C(C++) FORTRAN For REXX files use :- "A37,ASM,PAS,CMD,C,FOR," and replace the PL/S entries in the Language_colour entries. For Ada files use :- "A37,ASM,ADA,PLS,C,FOR," and replace the PAS entries in the Language_colour entries. If a file extension is an alias then place the extensions in parenthesis, e.g. "A37,ASM,PAS,PLS,(C,CPP),FOR,". Comment_start specifies the first two characters of the start of a comment. The string must be œ12 characters. The 6 pairs are used for :- 370 assembler 386 assembler PASCAL, for Ada specify Comment_start="* ; --/*/*C " PL/S, PL/AS etc. C FORTRAN The default value is Comment_start="* ; { /*/*C ". If the second character of the pair is a blank then the comment is assumed to begin with a single character. Comment_end specifies the last two characters of the comment. The string must be œ12 characters. The 6 pairs are used as in Comment_start. String_start specifies the string delimiter characters. Blanks are ignored. The string must be <=6 characters. The default value is Comment_end=" } */*/ ". If the second character of the pair is a blank then the comment is assumed to terminate with a single character. Precedent_C specifies the C language keywords which precede a procedure, e.g. int, char, etc. The string must be <=64 characters and terminated by a comma. Language_colour defines the highlight colours for key words. Up to 255 entries may be defined as follows :- file_type,key_word,colour,scan_length and are terminated by .END, invalid entries are ignored. The colour may be a single colour or an expression viz. :- (,,) The case and spaces within the keyword are significant, {the first character is used for the initial scan so a space would reduce the performance}. The keywords must be <=12 characters. {Colours may take the values :BLUE, DARKCYAN, BLACK, DARKBLUE, DARKPINK, DARKGRAY, DARKRED, DARKGREEN, BROWN, CYAN, RED, GREEN ,PINK, YELLOW, PALEGRAY, DEFAULT, WHITE (ORANGE, PURPLE, PALEGREEN, PALEBLUE)} Language_operator defines the operator keywords for each language. The second value indicates how to process the keyword, viz. < or > indicate the scan direction from the keyword to locate the label, 'P' or 'C' indicates that the keyword specifies an entry point or call, ':' indicates that the label will be followed by a colon, '2' indicates that the second label following a ',' is to be used. Up to 32 entries may be defined as follows :- file_type,<º>CºP[:][2],keyword and are terminated by '.END', invalid entries are ignored. The keywords must be <=12 characters. The C-language procedure values are supplied on the Precedent_C keyword. Window specifies the initial window position. A suitable value for 8515 and 8516 type screens may be - (0,60,800,600). If no profile is specified then Window=(0,60,420,635) is assumed. When the main window is closed its position will be remembered. Transfer_pgm specifies the programme name invoked from the Allocate widow. The data from the COMBO box is passed without modification to the Transfer_pgm when the Transfer button is selected. Tool bar ======== The Tool bar may be used to set an option etc. quickly. The Tool bar position and state will be remembered when the Alpha programme is closed. The following buttons are available :- - Hide/re-instate highlighted records from display. - Display/Create structure List box. - Toggle statement No. display. - Copy highlighted records to Clipboard. - Cascade Child windows. - Tile Child windows. - Toggle Tab expansion. - Toggle Include option. - Repeat last Locate command. - display the record references to the highlighted label. - suppress/display the comments in a language file. If a single line is scrolled then the comment suppression will be disabled. - Edit the current line. - Save the file. - Compile file - Copy the selected records to the Clipboard and erase from from memory. - Overwrite the current line with records from the Clipboard. - Delete records from memory. - Re-insert the last deleted records. - Clear select area. - Switch to/from box mode select. - Convert select area to upper/lower case. - Search current directory for string. If mouse button 2 is held down on a button then a small help balloon will be displayed. The structure of the Tool bar may be modified by using the "T" page of the Configure notebook. If the Tool bar is in the menu then if button 2 is held down and moved to a new position the button will be moved. Add/Modify a language ===================== Alpha has within it (hard coded) routines which understand certain language features e.g. 370 Assembler labels start in start in column 1, procedures are invoked by BAL, BAS etc. and PASCAL procedures are preceded by FUNCTION or PROCEDURE(7) etc.. There are 6 such languages 'understood' by Alpha, viz. :- 370 Assembler 386 Assembler PASCAL (Ada) PL/AS (PL/I, REXX) C FORTRAN Because Ada is similar to PASCAL and PL/I & REXX are similar to PL/AS, in respect to procedure calls etc., you can also analyse these languages by pretending they are type 3 & 4 respectively. However, you can interpret any language/file type (use the highlighting facility) by supplying extra definitions in a profile which is specified as a parameter to Alpha e.g. START ALPHA /p profile_name A sample profile (ALPHA.PRF) is provided in the package, which includes comments explaining the use of the keywords. This may be edited to change/add a file extension by modifying the following keywords :- File_type - list of file extensions up to 64 characters Comment_start - list of comment start character pairs (blank is ignored) up to 12 characters. Comment_end - list of comment end character pairs (blank is ignored) up to 12 characters. String_start - list of string delimiter characters (blank is ignored) up to 6 characters. Precedent_C - list of procedure keywords for language 5 which precede a procedure definition, up to 64 characters. Language_colour - list of keyword definitions file_type,keyword,colour,maximum scan length Language_operator - list of language operator values and attributes file_type,atributes,keyword e.g. to add language XYZ with a routine call 'ICALL routine_name' with similar structure to PL/S the profile would include the following statements :- File_type="A37,ASM,PAS,XYZ,C,FOR," Language_colour XYZ,ICALL,DARKGREEN,72 XYZ,Next_key ,RED,72 .END Language_operator XYZ,>C,ICALL .END Only the first 6 language types will allow the Expand and Structure operations to be effective. This implies that you could not use all the features of Alpha for a new language which did not have the call/label syntax of one of the existing languages. The ALPHA programme scans the keyword table in the order specified in the profile, so a later entry may replace a former entry. Writing a parser exit DLL ========================= If the DLL, ALPHAE.DLL, has been provided in the LIBPATH then the procedure Alpha_parse_exit will be called from the WM_PAINT child window procedure. A sample source module ALPHAE.C is provided which may be used to create a DLL with a parser exit procedure. This module may be used to write the records to the child window. Changes to the ALPHA package since August 1994 =============================================== 1) Ctrl+h - Hide/restore selected records. 2) Parse exit from WM_PAINT procedure. 3) Delete - erase a single character or the selected area. 4) Tool bar in menu. 5) Language_colour may contain forground and background colours. 6) Ctrl + mouse button 2 will cause a non-case sensitive search. 7) Ctrl+b - will re-insert the last deleted records. 8) Option Box - set box mode select. 9) Space+Ctrl - clear select area. 10) Ctrl+u - convert select area to upper/lower case. 11) Ctrl+g - Search current directory for string. 12) Ctrl+mouse button 1 - Create Pop-up menu for inserting special characters, displaying characters in hex. and instructions or Edit dialogue box. 13) Dis-assembly of ".EXE" files. 14) String_start - new profile keyword. Notes ===== 1 The data in the Allocate COMBO will be passed without modification to the Transfer_pgm. 2 The COMBO box will hold the previous three search strings entered. 3 The colours may take the values :BLUE, DARKCYAN, BLACK, DARKBLUE, DARKPINK, DARKGRAY, DARKRED, DARKGREEN, BROWN, CYAN, RED, GREEN ,PINK, YELLOW, PALEGRAY, DEFAULT, WHITE, ORANGE, PURPLE, PALEGREEN, PALEBLUE, COLOUR1. {The last five colours will not be available on VGA screens. The COLOUR1 value may be set by the sliders and will be remembered when Alpha is closed.} 4 If mouse button 1 is held down and moved to the bottom or top of the window the window will continue to scroll untill the button is released or the mouse is moved back within the window. 5 The ALPHA2.HLP file must be installed in the HELP path. 6 A sample profile is supplied with the name ALPHA.PRF. This file may be edited to alter the programme defaults. The profile is read by specifying /p as a parameter to the programme. 7 These keywords and attributes may be specified by the Language_operator keyword in the profile. =============== End of Alpha text file =============================